home *** CD-ROM | disk | FTP | other *** search
/ Chip 2007 January, February, March & April / Chip-Cover-CD-2007-02.iso / Pakiet bezpieczenstwa / mini Pentoo LiveCD 2006.1 / mpentoo-2006.1.iso / livecd.squashfs / usr / include / gaim / ft.h < prev    next >
Encoding:
C/C++ Source or Header  |  2005-10-18  |  15.9 KB  |  579 lines
  1. /**
  2.  * @file ft.h File Transfer API
  3.  * @ingroup core
  4.  *
  5.  * gaim
  6.  *
  7.  * Gaim is the legal property of its developers, whose names are too numerous
  8.  * to list here.  Please refer to the COPYRIGHT file distributed with this
  9.  * source distribution.
  10.  *
  11.  * This program is free software; you can redistribute it and/or modify
  12.  * it under the terms of the GNU General Public License as published by
  13.  * the Free Software Foundation; either version 2 of the License, or
  14.  * (at your option) any later version.
  15.  *
  16.  * This program is distributed in the hope that it will be useful,
  17.  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  18.  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  19.  * GNU General Public License for more details.
  20.  *
  21.  * You should have received a copy of the GNU General Public License
  22.  * along with this program; if not, write to the Free Software
  23.  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  24.  */
  25. #ifndef _GAIM_FT_H_
  26. #define _GAIM_FT_H_
  27.  
  28. /**************************************************************************/
  29. /** Data Structures                                                       */
  30. /**************************************************************************/
  31. typedef struct _GaimXfer GaimXfer;
  32.  
  33. #include "account.h"
  34.  
  35. /**
  36.  * Types of file transfers.
  37.  */
  38. typedef enum
  39. {
  40.     GAIM_XFER_UNKNOWN = 0,  /**< Unknown file transfer type. */
  41.     GAIM_XFER_SEND,         /**< File sending.               */
  42.     GAIM_XFER_RECEIVE       /**< File receiving.             */
  43.  
  44. } GaimXferType;
  45.  
  46. /**
  47.  * The different states of the xfer.
  48.  */
  49. typedef enum
  50. {
  51.     GAIM_XFER_STATUS_UNKNOWN = 0,   /**< Unknown, the xfer may be null. */
  52.     GAIM_XFER_STATUS_NOT_STARTED,   /**< It hasn't started yet. */
  53.     GAIM_XFER_STATUS_ACCEPTED,      /**< Receive accepted, but destination file not selected yet */
  54.     GAIM_XFER_STATUS_STARTED,       /**< gaim_xfer_start has been called. */
  55.     GAIM_XFER_STATUS_DONE,          /**< The xfer completed successfully. */
  56.     GAIM_XFER_STATUS_CANCEL_LOCAL,  /**< The xfer was canceled by us. */
  57.     GAIM_XFER_STATUS_CANCEL_REMOTE  /**< The xfer was canceled by the other end, or we couldn't connect. */
  58. } GaimXferStatusType;
  59.  
  60. /**
  61.  * File transfer UI operations.
  62.  *
  63.  * Any UI representing a file transfer must assign a filled-out
  64.  * GaimXferUiOps structure to the gaim_xfer.
  65.  */
  66. typedef struct
  67. {
  68.     void (*new_xfer)(GaimXfer *xfer);
  69.     void (*destroy)(GaimXfer *xfer);
  70.     void (*add_xfer)(GaimXfer *xfer);
  71.     void (*update_progress)(GaimXfer *xfer, double percent);
  72.     void (*cancel_local)(GaimXfer *xfer);
  73.     void (*cancel_remote)(GaimXfer *xfer);
  74.  
  75. } GaimXferUiOps;
  76.  
  77. /**
  78.  * A core representation of a file transfer.
  79.  */
  80. struct _GaimXfer
  81. {
  82.     guint ref;                    /**< The reference count.                 */
  83.     GaimXferType type;            /**< The type of transfer.               */
  84.  
  85.     GaimAccount *account;         /**< The account.                        */
  86.  
  87.     char *who;                    /**< The person on the other end of the
  88.                                        transfer.                           */
  89.  
  90.     char *message;                /**< A message sent with the request     */
  91.     char *filename;               /**< The name sent over the network.     */
  92.     char *local_filename;         /**< The name on the local hard drive.   */
  93.     size_t size;                  /**< The size of the file.               */
  94.  
  95.     FILE *dest_fp;                /**< The destination file pointer.       */
  96.  
  97.     char *remote_ip;              /**< The remote IP address.              */
  98.     int local_port;               /**< The local port.                     */
  99.     int remote_port;              /**< The remote port.                    */
  100.  
  101.     int fd;                       /**< The socket file descriptor.         */
  102.     int watcher;                  /**< Watcher.                            */
  103.  
  104.     size_t bytes_sent;            /**< The number of bytes sent.           */
  105.     size_t bytes_remaining;       /**< The number of bytes remaining.      */
  106.  
  107.     GaimXferStatusType status;    /**< File Transfer's status.             */
  108.  
  109.     /* I/O operations. */
  110.     struct
  111.     {
  112.         void (*init)(GaimXfer *xfer);
  113.         void (*request_denied)(GaimXfer *xfer);
  114.         void (*start)(GaimXfer *xfer);
  115.         void (*end)(GaimXfer *xfer);
  116.         void (*cancel_send)(GaimXfer *xfer);
  117.         void (*cancel_recv)(GaimXfer *xfer);
  118.         ssize_t (*read)(char **buffer, GaimXfer *xfer);
  119.         ssize_t (*write)(const char *buffer, size_t size, GaimXfer *xfer);
  120.         void (*ack)(GaimXfer *xfer, const char *buffer, size_t size);
  121.  
  122.     } ops;
  123.  
  124.     GaimXferUiOps *ui_ops;            /**< UI-specific operations. */
  125.     void *ui_data;                    /**< UI-specific data.       */
  126.  
  127.     void *data;                       /**< prpl-specific data.     */
  128. };
  129.  
  130. #ifdef __cplusplus
  131. extern "C" {
  132. #endif
  133.  
  134. /**************************************************************************/
  135. /** @name File Transfer API                                               */
  136. /**************************************************************************/
  137. /*@{*/
  138.  
  139. /**
  140.  * Creates a new file transfer handle.
  141.  * This is called by prpls.
  142.  * The handle starts with a ref count of 1, and this reference
  143.  * is owned by the core. The prpl normally does not need to
  144.  * gaim_xfer_ref or unref.
  145.  *
  146.  * @param account The account sending or receiving the file.
  147.  * @param type    The type of file transfer.
  148.  * @param who     The name of the remote user.
  149.  *
  150.  * @return A file transfer handle.
  151.  */
  152. GaimXfer *gaim_xfer_new(GaimAccount *account,
  153.                                 GaimXferType type, const char *who);
  154.  
  155. /**
  156.  * Increases the reference count on a GaimXfer.
  157.  * Please call gaim_xfer_unref later.
  158.  *
  159.  * @param xfer A file transfer handle.
  160.  */
  161. void gaim_xfer_ref(GaimXfer *xfer);
  162.  
  163. /**
  164.  * Decreases the reference count on a GaimXfer.
  165.  * If the reference reaches 0, gaim_xfer_destroy (an internal function)
  166.  * will destroy the xfer. It calls the ui destroy cb first.
  167.  * Since the core keeps a ref on the xfer, only an erroneous call to
  168.  * this function will destroy the xfer while still in use.
  169.  *
  170.  * @param xfer A file transfer handle.
  171.  */
  172. void gaim_xfer_unref(GaimXfer *xfer);
  173.  
  174. /**
  175.  * Requests confirmation for a file transfer from the user. If receiving
  176.  * a file which is known at this point, this requests user to accept and
  177.  * save the file. If the filename is unknown (not set) this only requests user
  178.  * to accept the file transfer. In this case protocol must call this function
  179.  * again once the filename is available.
  180.  *
  181.  * @param xfer The file transfer to request confirmation on.
  182.  */
  183. void gaim_xfer_request(GaimXfer *xfer);
  184.  
  185. /**
  186.  * Called if the user accepts the file transfer request.
  187.  *
  188.  * @param xfer     The file transfer.
  189.  * @param filename The filename.
  190.  */
  191. void gaim_xfer_request_accepted(GaimXfer *xfer, const char *filename);
  192.  
  193. /**
  194.  * Called if the user rejects the file transfer request.
  195.  *
  196.  * @param xfer The file transfer.
  197.  */
  198. void gaim_xfer_request_denied(GaimXfer *xfer);
  199.  
  200. /**
  201.  * Returns the type of file transfer.
  202.  *
  203.  * @param xfer The file transfer.
  204.  *
  205.  * @return The type of the file transfer.
  206.  */
  207. GaimXferType gaim_xfer_get_type(const GaimXfer *xfer);
  208.  
  209. /**
  210.  * Returns the account the file transfer is using.
  211.  *
  212.  * @param xfer The file transfer.
  213.  *
  214.  * @return The account.
  215.  */
  216. GaimAccount *gaim_xfer_get_account(const GaimXfer *xfer);
  217.  
  218. /**
  219.  * Returns the status of the xfer.
  220.  *
  221.  * @param xfer The file transfer.
  222.  *
  223.  * @return The status.
  224.  */
  225. GaimXferStatusType gaim_xfer_get_status(const GaimXfer *xfer);
  226.  
  227. /**
  228.  * Returns true if the file transfer was canceled.
  229.  *
  230.  * @param xfer The file transfer.
  231.  *
  232.  * @return Whether or not the transfer was canceled.
  233.  */
  234. gboolean gaim_xfer_is_canceled(const GaimXfer *xfer);
  235.  
  236. /**
  237.  * Returns the completed state for a file transfer.
  238.  *
  239.  * @param xfer The file transfer.
  240.  *
  241.  * @return The completed state.
  242.  */
  243. gboolean gaim_xfer_is_completed(const GaimXfer *xfer);
  244.  
  245. /**
  246.  * Returns the name of the file being sent or received.
  247.  *
  248.  * @param xfer The file transfer.
  249.  *
  250.  * @return The filename.
  251.  */
  252. const char *gaim_xfer_get_filename(const GaimXfer *xfer);
  253.  
  254. /**
  255.  * Returns the file's destination filename,
  256.  *
  257.  * @param xfer The file transfer.
  258.  *
  259.  * @return The destination filename.
  260.  */
  261. const char *gaim_xfer_get_local_filename(const GaimXfer *xfer);
  262.  
  263. /**
  264.  * Returns the number of bytes sent so far.
  265.  *
  266.  * @param xfer The file transfer.
  267.  *
  268.  * @return The number of bytes sent.
  269.  */
  270. size_t gaim_xfer_get_bytes_sent(const GaimXfer *xfer);
  271.  
  272. /**
  273.  * Returns the number of bytes received so far.
  274.  *
  275.  * @param xfer The file transfer.
  276.  *
  277.  * @return The number of bytes received.
  278.  */
  279. size_t gaim_xfer_get_bytes_remaining(const GaimXfer *xfer);
  280.  
  281. /**
  282.  * Returns the size of the file being sent or received.
  283.  *
  284.  * @param xfer The file transfer.
  285.  *
  286.  * @return The total size of the file.
  287.  */
  288. size_t gaim_xfer_get_size(const GaimXfer *xfer);
  289.  
  290. /**
  291.  * Returns the current percentage of progress of the transfer.
  292.  *
  293.  * This is a number between 0 (0%) and 1 (100%).
  294.  *
  295.  * @param xfer The file transfer.
  296.  *
  297.  * @return The percentage complete.
  298.  */
  299. double gaim_xfer_get_progress(const GaimXfer *xfer);
  300.  
  301. /**
  302.  * Returns the local port number in the file transfer.
  303.  *
  304.  * @param xfer The file transfer.
  305.  *
  306.  * @return The port number on this end.
  307.  */
  308. unsigned int gaim_xfer_get_local_port(const GaimXfer *xfer);
  309.  
  310. /**
  311.  * Returns the remote IP address in the file transfer.
  312.  *
  313.  * @param xfer The file transfer.
  314.  *
  315.  * @return The IP address on the other end.
  316.  */
  317. const char *gaim_xfer_get_remote_ip(const GaimXfer *xfer);
  318.  
  319. /**
  320.  * Returns the remote port number in the file transfer.
  321.  *
  322.  * @param xfer The file transfer.
  323.  *
  324.  * @return The port number on the other end.
  325.  */
  326. unsigned int gaim_xfer_get_remote_port(const GaimXfer *xfer);
  327.  
  328. /**
  329.  * Sets the completed state for the file transfer.
  330.  *
  331.  * @param xfer      The file transfer.
  332.  * @param completed The completed state.
  333.  */
  334. void gaim_xfer_set_completed(GaimXfer *xfer, gboolean completed);
  335.  
  336. /**
  337.  * Sets the filename for the file transfer.
  338.  *
  339.  * @param xfer     The file transfer.
  340.  * @param message The message.
  341.  */
  342. void gaim_xfer_set_message(GaimXfer *xfer, const char *message);
  343.  
  344. /**
  345.  * Sets the filename for the file transfer.
  346.  *
  347.  * @param xfer     The file transfer.
  348.  * @param filename The filename.
  349.  */
  350. void gaim_xfer_set_filename(GaimXfer *xfer, const char *filename);
  351.  
  352. /**
  353.  * Sets the local filename for the file transfer.
  354.  *
  355.  * @param xfer     The file transfer.
  356.  * @param filename The filename
  357.  */
  358. void gaim_xfer_set_local_filename(GaimXfer *xfer, const char *filename);
  359.  
  360. /**
  361.  * Sets the size of the file in a file transfer.
  362.  *
  363.  * @param xfer The file transfer.
  364.  * @param size The size of the file.
  365.  */
  366. void gaim_xfer_set_size(GaimXfer *xfer, size_t size);
  367.  
  368. /**
  369.  * Returns the UI operations structure for a file transfer.
  370.  *
  371.  * @param xfer The file transfer.
  372.  *
  373.  * @return The UI operations structure.
  374.  */
  375. GaimXferUiOps *gaim_xfer_get_ui_ops(const GaimXfer *xfer);
  376.  
  377. /**
  378.  * Sets the read function for the file transfer.
  379.  *
  380.  * @param xfer The file transfer.
  381.  * @param fnc  The read function.
  382.  */
  383. void gaim_xfer_set_read_fnc(GaimXfer *xfer,
  384.         ssize_t (*fnc)(char **, GaimXfer *));
  385.  
  386. /**
  387.  * Sets the write function for the file transfer.
  388.  *
  389.  * @param xfer The file transfer.
  390.  * @param fnc  The write function.
  391.  */
  392. void gaim_xfer_set_write_fnc(GaimXfer *xfer,
  393.         ssize_t (*fnc)(const char *, size_t, GaimXfer *));
  394.  
  395. /**
  396.  * Sets the acknowledge function for the file transfer.
  397.  *
  398.  * @param xfer The file transfer.
  399.  * @param fnc  The acknowledge function.
  400.  */
  401. void gaim_xfer_set_ack_fnc(GaimXfer *xfer,
  402.         void (*fnc)(GaimXfer *, const char *, size_t));
  403.  
  404. /**
  405.  * Sets the function to be called if the request is denied.
  406.  *
  407.  * @param xfer The file transfer.
  408.  * @param fnc The request denied prpl callback.
  409.  */
  410. void gaim_xfer_set_request_denied_fnc(GaimXfer *xfer, void (*fnc)(GaimXfer *));
  411.  
  412. /**
  413.  * Sets the transfer initialization function for the file transfer.
  414.  *
  415.  * This function is required, and must call gaim_xfer_start() with
  416.  * the necessary parameters. This will be called if the file transfer
  417.  * is accepted by the user.
  418.  *
  419.  * @param xfer The file transfer.
  420.  * @param fnc  The transfer initialization function.
  421.  */
  422. void gaim_xfer_set_init_fnc(GaimXfer *xfer, void (*fnc)(GaimXfer *));
  423.  
  424. /**
  425.  * Sets the start transfer function for the file transfer.
  426.  *
  427.  * @param xfer The file transfer.
  428.  * @param fnc  The start transfer function.
  429.  */
  430. void gaim_xfer_set_start_fnc(GaimXfer *xfer, void (*fnc)(GaimXfer *));
  431.  
  432. /**
  433.  * Sets the end transfer function for the file transfer.
  434.  *
  435.  * @param xfer The file transfer.
  436.  * @param fnc  The end transfer function.
  437.  */
  438. void gaim_xfer_set_end_fnc(GaimXfer *xfer, void (*fnc)(GaimXfer *));
  439.  
  440. /**
  441.  * Sets the cancel send function for the file transfer.
  442.  *
  443.  * @param xfer The file transfer.
  444.  * @param fnc  The cancel send function.
  445.  */
  446. void gaim_xfer_set_cancel_send_fnc(GaimXfer *xfer, void (*fnc)(GaimXfer *));
  447.  
  448. /**
  449.  * Sets the cancel receive function for the file transfer.
  450.  *
  451.  * @param xfer The file transfer.
  452.  * @param fnc  The cancel receive function.
  453.  */
  454. void gaim_xfer_set_cancel_recv_fnc(GaimXfer *xfer, void (*fnc)(GaimXfer *));
  455.  
  456. /**
  457.  * Reads in data from a file transfer stream.
  458.  *
  459.  * @param xfer   The file transfer.
  460.  * @param buffer The buffer that will be created to contain the data.
  461.  *
  462.  * @return The number of bytes read, or -1.
  463.  */
  464. ssize_t gaim_xfer_read(GaimXfer *xfer, char **buffer);
  465.  
  466. /**
  467.  * Writes data to a file transfer stream.
  468.  *
  469.  * @param xfer   The file transfer.
  470.  * @param buffer The buffer to read the data from.
  471.  * @param size   The number of bytes to write.
  472.  *
  473.  * @return The number of bytes written, or -1.
  474.  */
  475. ssize_t gaim_xfer_write(GaimXfer *xfer, const char *buffer, size_t size);
  476.  
  477. /**
  478.  * Starts a file transfer.
  479.  *
  480.  * Either @a fd must be specified <i>or</i> @a ip and @a port on a
  481.  * file receive transfer. On send, @a fd must be specified, and
  482.  * @a ip and @a port are ignored.
  483.  *
  484.  * @param xfer The file transfer.
  485.  * @param fd   The file descriptor for the socket.
  486.  * @param ip   The IP address to connect to.
  487.  * @param port The port to connect to.
  488.  */
  489. void gaim_xfer_start(GaimXfer *xfer, int fd, const char *ip,
  490.                      unsigned int port);
  491.  
  492. /**
  493.  * Ends a file transfer.
  494.  *
  495.  * @param xfer The file transfer.
  496.  */
  497. void gaim_xfer_end(GaimXfer *xfer);
  498.  
  499. /**
  500.  * Adds a new file transfer to the list of file transfers. Call this only
  501.  * if you are not using gaim_xfer_start.
  502.  *
  503.  * @param xfer The file transfer.
  504.  */
  505. void gaim_xfer_add(GaimXfer *xfer);
  506.  
  507. /**
  508.  * Cancels a file transfer on the local end.
  509.  *
  510.  * @param xfer The file transfer.
  511.  */
  512. void gaim_xfer_cancel_local(GaimXfer *xfer);
  513.  
  514. /**
  515.  * Cancels a file transfer from the remote end.
  516.  *
  517.  * @param xfer The file transfer.
  518.  */
  519. void gaim_xfer_cancel_remote(GaimXfer *xfer);
  520.  
  521. /**
  522.  * Displays a file transfer-related error message.
  523.  *
  524.  * This is a wrapper around gaim_notify_error(), which automatically
  525.  * specifies a title ("File transfer to <i>user</i> aborted" or
  526.  * "File Transfer from <i>user</i> aborted").
  527.  *
  528.  * @param type The type of file transfer.
  529.  * @param who  The user on the other end of the transfer.
  530.  * @param msg  The message to display.
  531.  */
  532. void gaim_xfer_error(GaimXferType type, const char *who, const char *msg);
  533.  
  534. /**
  535.  * Updates file transfer progress.
  536.  *
  537.  * @param xfer      The file transfer.
  538.  */
  539. void gaim_xfer_update_progress(GaimXfer *xfer);
  540.  
  541. /**
  542.  * Displays a file transfer-related message in the conversation window
  543.  *
  544.  * This is a wrapper around gaim_conversation_write
  545.  *
  546.  * @param xfer The file transfer to which this message relates.
  547.  * @param message The message to display.
  548.  * @param gboolean Is this an error message?.
  549.  */
  550. void gaim_xfer_conversation_write(GaimXfer *xfer, char *message, gboolean is_error);
  551. /*@}*/
  552.  
  553. /**************************************************************************/
  554. /** @name UI Registration Functions                                       */
  555. /**************************************************************************/
  556. /*@{*/
  557.  
  558. /**
  559.  * Sets the UI operations structure to be used in all gaim file transfers.
  560.  *
  561.  * @param ops The UI operations structure.
  562.  */
  563. void gaim_xfers_set_ui_ops(GaimXferUiOps *ops);
  564.  
  565. /**
  566.  * Returns the UI operations structure to be used in all gaim file transfers.
  567.  *
  568.  * @return The UI operations structure.
  569.  */
  570. GaimXferUiOps *gaim_xfers_get_ui_ops(void);
  571.  
  572. /*@}*/
  573.  
  574. #ifdef __cplusplus
  575. }
  576. #endif
  577.  
  578. #endif /* _GAIM_FT_H_ */
  579.